Initial commit

1 files changed, 861 insertions, 0 deletions

diff --git a/pkg/images/imcoords/doc/skyctran.hlp b/pkg/images/imcoords/doc/skyctran.hlp
new file mode 100644
index 00000000..d91dd983
--- /dev/null
+++ b/pkg/images/imcoords/doc/skyctran.hlp
@@ -0,0 +1,861 @@
+.help skyctran Jun99 images.imcoords
+.ih
+NAME
+skyctran -- convert astronomical coordinates from one system to another
+.ih
+USAGE
+skyctran input output insystem outsystem
+.ih
+PARAMETERS
+.ls input
+The source of the input coordinates. The options are:
+.ls <filename>
+The list of input coordinate files. Coordinates may be entered by hand by
+setting input to "STDIN". A STDIN coordinate list is terminated by typing
+q or <EOF> (usually <ctrl/d> or <ctrl/z>).
+.le
+.ls imcursor
+If the input file name is equal to the reserved keyword "imcursor" the input
+coordinates are read from the image cursor and the input coordinate system
+is the coordinate system of the image specified by the insystem parameter.
+The coordinate list is terminated by typing q or  <EOF> (usually <ctrl/d> or
+<ctr/z>).
+.le
+.ls grid
+If the input file name is equal to the reserved
+keyword "grid", an \fInilng\fR by \fInilat\fR grid of equally spaced
+input coordinates
+is generating spanning the region defined by \fIilngmin\fR, \fIilngmax\fR,
+\fIilatmin\fR, \fIilatmax\fR.
+.le
+.le
+.ls output
+The list of output coordinate files. The number of output files must be
+equal to one or the number of input files. Results may be printed on the
+terminal by setting output to "STDOUT".
+.le
+.ls insystem, outsystem
+The input and output celestial coordinate systems. The options are
+the following:
+.ls <imagename> [wcs]
+The celestial coordinate system is the world coordinate system of the image
+<imagename> and the input or output pixel coordinates may be in the
+"logical", "tv", "physical" or "world" coordinate systems. If wcs is not
+specified "logical" is assumed, unless the input coordinates are read from the
+image cursor, in which case "tv" is assumed. The image celestial coordinate
+system must be one of the valid FITS celestial coordinate systems:
+equatorial (FK4, FK4-NO-E, FK5, ICRS, or GAPPT), ecliptic, galactic, or
+supergalactic.
+.le
+.ls icrs [equinox] [epoch]
+The International Celestial Reverence System where equinox is
+a Julian or Besselian epoch e.g. J2000.0  or B1980.0.
+Equinoxes without the J / j or B / b prefix are treated as Julian epochs.
+The default value of equinox is J2000.0.
+Epoch is a Besselian epoch, a Julian epoch, or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Julian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian date.  If undefined epoch defaults to equinox.
+.le
+.ls equinox [epoch]
+The equatorial mean place post-IAU 1976 (FK5) system if equinox is a
+Julian epoch, e.g. J2000.0 or 2000.0, or the equatorial mean place
+pre-IAU 1976 system (FK4) if equinox is a Besselian epoch, e.g. B1950.0
+or 1950.0. Julian equinoxes are prefixed by a J or j, Besselian equinoxes
+by a B or b. Equinoxes without the J / j or B / b prefix are treated as
+Besselian epochs if they are < 1984.0, Julian epochs if they are >= 1984.0.
+Epoch is the epoch of the observation and may be a Julian
+epoch, a Besselian epoch, or a Julian date. Julian epochs
+are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to the epoch type of
+equinox if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian date.  If undefined epoch defaults to equinox.
+.le
+.ls fk5 [equinox] [epoch] 
+The equatorial mean place post-IAU 1976 (FK5) system where equinox is
+a Julian or Besselian epoch e.g. J2000.0  or B1980.0.
+Equinoxes without the J / j or B / b prefix are treated as Julian epochs.
+The default value of equinox is J2000.0.
+Epoch is a Besselian epoch, a Julian epoch, or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Julian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian date.  If undefined epoch defaults to equinox.
+.le
+.ls fk4 [equinox] [epoch]
+The equatorial mean place pre-IAU 1976 (FK4) system where equinox is a
+Besselian or Julian epoch e.g. B1950.0  or J2000.0,
+and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the
+observation.
+Equinoxes without the J / j or B / b prefix are treated
+as Besselian epochs. The default value of equinox is B1950.0. Epoch
+is a Besselian epoch, a Julian epoch, or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Besselian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian date.  If undefined epoch defaults to equinox.
+.le
+.ls noefk4 [equinox] [epoch]
+The equatorial mean place pre-IAU 1976 (FK4) system but without the E-terms
+where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0,
+and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the
+observation.
+Equinoxes without the J / j or B / b prefix are treated
+as Besselian epochs. The default value of equinox is B1950.0.
+Epoch is a Besselian epoch, a Julian epoch, or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Besselian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian day.  If undefined epoch defaults to equinox.
+.le
+.ls apparent epoch 
+The equatorial geocentric apparent place post-IAU 1976 system where
+epoch is the epoch of observation.
+Epoch is a Besselian epoch, a Julian epoch or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Besselian
+epochs if the epoch value < 1984.0, Julian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian date.
+.le
+.ls ecliptic epoch
+The ecliptic coordinate system where epoch is the epoch of observation.
+Epoch is a Besselian epoch, a Julian epoch, or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Besselian epochs
+if the epoch values < 1984.0, Julian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian day.
+.le
+.ls galactic [epoch]
+The IAU 1958 galactic coordinate system.
+Epoch is a Besselian epoch, a Julian epoch or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Besselian
+epochs if the epoch value < 1984.0, Julian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian date. The default value of epoch is B1950.0.
+.le
+.ls supergalactic [epoch]
+The deVaucouleurs supergalactic coordinate system.
+Epoch is a Besselian epoch, a Julian epoch or a Julian date.
+Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
+Epochs without the J / j or B / b prefix default to Besselian
+epochs if the epoch value < 1984.0, Julian epochs
+if the epoch value <= 3000.0, otherwise epoch is interpreted as
+a Julian date. The default value of epoch is B1950.0.
+.le
+
+In all the above cases fields in [] are optional with the defaults as
+described. The epoch field for fk5, icrs, galactic, and supergalactic
+coordinate systems is required only if the input coordinates are in the
+equatorial fk4, noefk4, fk5, or icrs systems and proper motions are defined.
+.le
+.ls transform = no
+If transform = no the computed output coordinates are appended to the
+input line and the new extended line is written to the output file. If
+transform = yes the computed output coordinates replace
+the input coordinates in the input line and the edited line is written
+to the output file. Transform is always set to "no" if the input
+is from the unredirected standard input.
+.le
+.ls lngcolumn = 1, latcolumn = 2
+The columns in the input file containing the x/ra/longitude and
+y/dec/latitude coordinates. Lngcolumn and latcolumn are always 1 and
+2 if the input is from the unredirected standard input.
+.le
+.ls plngcolumn = INDEF, platcolumn = INDEF
+The columns in the input file containing the ra and dec proper motions
+in " / year. If plngcolumn and platcolumn are INDEF the proper motions
+are assumed to be undefined. Proper motions
+are used only if the input coordinate system is equatorial fk4, noefk4,
+fk5, or icrs.  Plngcolumn and platcolumn are always 3 and 4 if the input is from
+the unredirected standard input.
+.le
+.ls pxcolumn = INDEF, rvcolumn = INDEF
+The columns in the input file containing the parallax and radial velocity in
+in " and km / sec respectively. If pxcolumn and rvcolumn are INDEF, the 
+parallax and radial velocities are assumed to be 0.0 and 0.0.
+Parallaxes and radial velocities are only used if proper motions are
+defined. Pxcolumn and rvcolumn are always 5 and 6 if the input is from the
+unredirected standard input.
+.le
+.ls ilngmin = INDEF, ilngmax = INDEF, ilatmin = INDEF, ilatmax = INDEF 
+The lower and upper limits of the coordinate grid if \fIinput\fR =
+"grid".
+Ilngmin and ilngmax default to 1.0, 1.0, 0.0, 0.0, 0.0 and, 2048.0, ncols, 24.0,
+360.0, and TWOPI for coordinates in units of INDEF, pixels, hours, degrees,
+and radians respectively. Ilatmin and ilatmax default to 1.0, 1.0,
+-90.0, -90.0, -HALFPI and, 2048.0, nlines, 90.0, 90.0, and HALFPI
+for units of INDEF, pixels, degrees, degrees, and radians respectively.
+.le
+.ls nilng = 10, nilat = 10
+The size of the computed coordinate grid if \fIinput\fR = "grid".
+.le
+.ls ilngunits = "", ilatunits = ""
+The units of the input ra/longitude and dec/latitude coordinates.
+The options are:
+.ls hours
+Read the sky coordinates in hours.
+.le
+.ls degrees
+Read the sky coordinates in degrees.
+.le
+.ls radians
+Read the sky coordinates in radians.
+.le
+
+If the input system is the <imagename> [logical/tv/physical]
+system, pixel units are assumed regardless of the values
+of ilngunits or ilatunits.  The default ilngunits and
+ilatunits values are
+hours and degrees for the equatorial coordinate systems and degrees and
+degrees for the remaining sky coordinate systems.
+.le
+.ls ilngformat = "", ilatformat = ""
+The output format of the input x/ra/longitude and y/dec/latitude coordinates
+if \fIinput\fR = "grid".
+The options are discussed in the formats section of the help page below.
+If the input coordinate system is the <imagename> [logical/tv/physical]
+system, default formats of %10.3f and %10.3f are assumed regardless
+of the values of ilngunits and ilatunits. Otherwise default formats
+of %12.3h, %12.2h, and %13.7g are assumed for input units of "hours", "degrees",
+and "radians" respectively. For values of \fIinput\fR other than "grid"
+the output formats of the input coordinates are the same as the input
+formats.
+.le
+.ls olngunits = "", olatunits = ""
+The units of the output ra/longitude and dec/latitude coordinates.
+The options are:
+.ls hours
+Output the sky coordinates in hours.
+.le
+.ls degrees
+Output the sky coordinates in degrees.
+.le
+.ls radians
+Output the sky coordinates in radians.
+.le
+
+If the output system is the <imagename> [logical/tv/physical]
+system, pixel units are assumed regardless of the values
+of olngunits or olatunits.  The default olngunits and
+olatunits values are
+hours and degrees for the equatorial coordinate systems and degrees and
+degrees for the remaining sky coordinate systems.
+.le
+.ls olngformat = "", olatformat = ""
+The format of the computed x/ra/longitude and y/dec/latitude coordinates.
+The options are discussed in the formats section of the help page below.
+If the output coordinate system is the <imagename> [logical/tv/physical]
+system, default formats of %10.3f and %10.3f are assumed regardless
+of the values of olngunits and olatunits. Otherwise default formats
+of %12.3h, %12.2h, and %13.7g are assumed for output units of "hours",
+"degrees", and "radians" respectively.
+.le
+.ls icommands = ""
+The default image display cursor.
+.le
+.ls verbose = yes
+Print messages about actions taken by the task on the standard output?
+.le
+
+.ih
+DESCRIPTION
+
+SKYCTRAN converts coordinates in the input files
+\fIinput\fR from the input celestial coordinate system \fIinsystem\fR
+to the output celestial coordinate system \fIoutsystem\fR and writes the
+converted coordinates to the output files \fIoutput\fR. The input
+files may be simple text files, the standard input "STDIN",
+the image display cursor "imcursor", or a user specified coordinate grid.
+The output files may be simple
+text files or the standard output "STDOUT". SKYCTRAN may be used
+to change the units of the input coordinates, e.g. from degrees and degrees
+to hours and degrees, to precess the coordinates, to convert from one
+celestial coordinate system to another, e.g. from equatorial to ecliptic
+coordinates and vice versa, and to locate common objects in
+images whose fundamental coordinate systems are the same but observed at
+different epochs, e.g. FK4 B1950.0 and FK4 B1975.0, or different, e.g.
+equatorial FK4 B1950.0 and galactic.
+
+The input data are read from columns \fIlngcolumn\fR, \fIlatcolumn\fR,
+\fIplngcolumn\fR, \fIplatcolumn\fR, \fIpxcolumn\fR, and \fIrvcolumn\fR
+in the input files and if \fItransform\fR = yes, the converted coordinates are
+written to the same columns in the output files. If \fItransform\fR = "no",
+the converted coordinates are appended to the input line creating two
+additional columns in the output file. If the input file is the
+unredirected standard input then transpose is always "no". Comment lines, blanks
+lines, and lines for which the input coordinates could not be successfully
+decoded are passed on to the output file without modification.
+
+The input and output celestial coordinate systems \fIinsystem\fR and
+\fIoutsystem\fR must be one of the following: equatorial, ecliptic, galactic, or
+supergalactic.  The equatorial systems must be one of: 1) FK4, the mean
+place pre-IAU 1976 system, 2) FK4-NO-E, the same as FK4 but without the
+E-terms, 3) FK5, the mean place post-IAU 1976 system, 4) ICRS,
+the International Celestial Reference System, 5) GAPPT, the geocentric
+apparent place in the post-IAU 1976 system. 
+
+If \fIinsystem\fR or \fIoutsystem\fR is an image name then the celestial
+coordinate system is read from the image header. SKYCTRAN assumes that
+the celestial coordinate system is represented in the image header by
+the FITS keywords CTYPE, CRPIX, CRVAL, CD (or alternatively CDELT / CROTA),
+RADECSYS, EQUINOX (or EPOCH), and MJD-WCS (or MJD_OBS or DATE-OBS). USERS
+SHOULD TAKE NOTE THAT MJD-WCS IS CURRENTLY NEITHER A STANDARD OR
+PROPOSED FUTS STANDARD 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 permitted CTYPE values 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,
+
+If the image celestial coordinate system is equatorial, the value
+of the RADECSYS keyword specifies the fundamental equatorial system.
+The permitted values of RADECSYS are FK4, FK4-NO-E,
+FK5, ICRS, and GAPPT. If the RADECSYS keyword is not
+present in the image header, the values of the EQUINOX or EPOCH keywords
+in that order of precedence are used to determine the fundamental
+equatorial system. EQUINOX or EPOCH contain the
+epoch of the mean place and equinox for the FK4, FK4-NO-E, FK5, and ICRS
+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
+and ICRS systems.
+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 and ICRS systems. Users are
+strongly urged to use the EQUINOX keyword in preference to the EPOCH
+keyword if they must enter their own values of the equinox 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 input coordinate system epoch of the observation is also required
+if the input coordinate system is FK4, FK4-NO-E, FK5, or ICRS and proper motions
+are supplied.
+The epoch is specified, in order of precedence, by the values of
+the keywords MJD-WCS or MJD-OBS containing the modified Julian date
+(JD - 2400000.5) of
+the coordinate system, or the DATE-OBS keyword containing
+the date of the observation in the form DD/MM/YY, CCYY-MM-DD, or
+CCYY-MM-DDTHH:MM:SS.S. As the latter quantity may
+only be accurate to a day, the MJD-WCS or MJD-OBS specifications are
+preferable. If both
+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 as for the FK4, FK4-NO-E, FK5,
+and ICRS systems.
+
+If the celestial coordinate system is ecliptic the mean ecliptic and equinox of
+date are required. They are supplied via the MJD-WCS, MJD-OBS or DATE-OBS
+keywords as for the equatorial FK4, FK4-NO-E, FK5, ICRS, and GAPPT systems.
+
+If, the output coordinate system is galactic or supergalactic, the input
+coordinate system is FK4, FK4-NO-E, FK5, or ICRS and proper motions are
+supplied with the input coordinates, then the output epoch of the
+observation is also required. This is supplied via the MJD-WCS, MJD-OBS or
+DATE-OBS keywords as for the equatorial FK4, FK4-NO-E, FK5, ICRS, GAPPT,
+and ecliptic 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 (ra axis) = "RA--XXXX" CTYPE (dec axis) = "DEC-XXXX")
+WHERE XXXX IS THE PROJECTION TYPE, EVEN THOUGH THE SKYCTRAN TASK 
+SUPPORTS GALACTIC, ECLIPTIC, AND SUPERGALACTIC COORDINATES.
+
+USERS SHOULD ALSO REALIZE THAT IMAGE WORLD COORDINATE SYSTEM REPRESENTATION
+IN FITS IS STILL IN THE DRAFT STAGE. ALTHOUGH SKYCTRAN TRIES TO CONFORM TO
+THE CURRENT DRAFT PROPOSAL WHERE NO ADOPTED STANDARDS CURRENTLY EXIST, THE
+FINAL FITS STANDARD MAY DIFFER FROM THE ONE ADOPTED HERE.
+
+The IRAF builtin world coordinate systems "logical", "tv", "physical", and
+world are also supported. This means for example that users can begin
+with cursor coordinates in image 1, use the image header of image 1
+to transform the pixel coordinates to the celestial coordinate system of
+image 1, convert the image 1 celestial coordinates to celestial coordinates
+in the image 2 celestial coordinate system, and finally transform the
+celestial coordinate system 2 coordinates to pixel coordinates in image 2,
+all in one step.
+
+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.
+
+IF AN ERROR IS ENCOUNTERED WHEN DECODING THE INPUT OR OUTPUT WORLD COORDINATE
+SYSTEMS, THEN AN ERROR FLAG IS PRINTED IN THE OUTPUT FILE AND ON THE STANDARD
+OUTPUT IF \fIVERBOSE\fR IS YES, AND THE INPUT COORDINATES ARE COPIED TO THE
+OUTPUT COORDINATES WITHOUT CHANGE.
+
+\fIIlngunits\fR, \fIilatunits\fR, \fIolngunits\fR, and \fIolatunits\fR
+set the units of the input and output coordinate systems.
+If the input or output system is the <imagename> [logical/tv/physical]
+system pixel units are assumed regardless of the values
+of <i/o>lngunits or <i/o>latunits.  The default <i/o>lngunits and
+<i/o>latunits values are
+hours and degrees for the equatorial celestial coordinate system and
+degrees and degrees for the remaining celestial coordinate systems.
+
+The formats of the computed x/ra/longitude and y/dec/longitude coordinates
+are specified with the \fIolngformat\fR and \fIolatformat\fR parameters.
+The options are discussed in the formats section of the help page below.
+If the output coordinate system is the <imagename> [logical/tv/physical],
+default formats of %10.3f and %10.3f are assumed regardless
+of the values of olngunits and olatunits. Otherwise default formats
+of %12.3h, %12.2h, and %g are assumed for output units of "hours", "degrees",
+and "radians" respectively.
+
+.ih
+USER COMMANDS
+
+If the input file is STDIN the user can type in the input data by hand and
+set the input and output coordinate systems, the input and output coordinate
+units, and the output coordinate format interactively. The available commands
+are listed below.
+
+.nf
+	INTERACTIVE KEYSTROKE COMMANDS
+
+The following commands must be followed by a carriage return.
+
+?	Print help
+:	Execute colon command
+data	Measure object
+q	Exit task
+
+
+	VALID DATA STRING
+
+x/ra/long y/dec/lat [pmra pmdec [parallax radial velocity]]
+
+... x/ra/long y/dec/lat must be in pixels or the input units
+... pmra and pmdec must be in " / year
+... parallax must be in "
+... radial velocity must be in km / sec
+
+	COLON COMMANDS
+
+The following commands must be followed by a carriage return.
+
+:show				Show the input and output coordinate systems
+:isystem	[string]	Show / set the input coordinate system
+:osystem	[string]	Show / set the output coordinate system
+:iunits		[string string]	Show / set the input coordinate units
+:ounits		[string string]	Show / set the output coordinate units
+:oformat	[string string]	Show / set the output coordinate format
+
+	VALID INPUT AND OUTPUT COORDINATE SYSTEMS
+
+image [logical/tv/physical/world]
+equinox [epoch]
+noefk4 [equinox [epoch]]
+fk4 [equinox [epoch]]
+fk5 [equinox [epoch]]
+icrs [equinox [epoch]]
+apparent epoch
+ecliptic epoch
+galactic [epoch]
+supergalactic [epoch]
+
+	VALID INPUT AND OUTPUT CELESTIAL COORDINATE UNITS
+	          AND THEIR DEFAULT FORMATS
+
+hours		%12.3h
+degrees		%12.2h
+radians		%13.7h
+.fi
+
+.ih
+IMAGE CURSOR COMMANDS
+
+In interactive image cursor mode the user can set the input and output
+coordinate systems, the output coordinate units, and the output coordinate
+formats. The available commands are listed below.
+
+.nf
+	INTERACTIVE KEYSTROKE COMMANDS
+
+?	Print help
+:	Execute colon command
+spbar	Measure object
+q	Exit task
+
+
+	COLON COMMANDS
+
+:show				Show the input and output coordinate systems
+:isystem	[string]	Show / set the input coordinate system
+:osystem	[string]	Show / set the output coordinate system
+:ounits		[string string]	Show / set the output coordinate units
+:oformat	[string string]	Show / set the output coordinate format
+
+	VALID INPUT COORDINATE SYSTEMS
+
+image [tv]
+
+	VALID OUTPUT COORDINATE SYSTEMS
+
+image [logical/tv/physical/world]
+equinox [epoch]
+noefk4 [equinox [epoch]]
+fk4 [equinox [epoch]]
+fk5 [equinox [epoch]]
+icrs [equinox [epoch]]
+apparent epoch
+ecliptic epoch
+galactic [epoch]
+supergalactic [epoch]
+
+	VALID OUTPUT COORDINATE UNITS AND THEIR DEFAULT FORMATS
+
+hours		%12.3h
+degrees		%12.2h
+radians		%13.7g
+.fi
+
+
+.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 the 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 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. Precess the fk4 coordinates typed in by the user to the fk5 system with
+and without the proper motion values.
+
+.nf
+	cl> skyctran STDIN STDOUT fk4 fk5
+
+	# Insystem: fk4  Coordinates: equatorial FK4
+	#     Equinox: B1950.000 Epoch: B1950.00000000 MJD: 33281.92346
+	# Outsystem: fk5  Coordinates: equatorial FK5
+	#     Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000
+
+	# Input file: STDIN  Output file: STDOUT
+
+	... not including proper motion
+	13:28:43.2 27:18:01.1
+	13:28:43.2 27:18:01.1 13:31:03.855  27:02:35.13
+
+	... including proper motion
+	13:28:43.2 27:18:01.1 .36 -0.16
+	13:28:43.2 27:18:01.1 .36 -0.16 13:31:05.215  27:02:27.37
+
+	... change the output coordinate system to fk5 1975.0 and repeat
+	:os fk5 1975.0
+	:os
+
+	# Outsystem:  fk5 1975.0  Coordinates: equatorial FK5
+	#     Equinox: J1975.000 Epoch: J1975.00000000 MJD: 42413.25000
+
+	13:28:43.2 27:18:01.1
+	13:28:43.2 27:18:01.1 13:29:53.564  27:10:17.69
+
+	13:28:43.2 27:18:01.1 .36 -0.16
+	13:28:43.2 27:18:01.1 .36 -0.16 13:29:54.244  27:10:13.80
+
+	... type EOF to quit
+	<EOF>
+.fi
+
+2. Precess a list of RAS in hours and DECS in degrees in the FK5 system
+equinox 1980.0 to equinox 2000.0 and write both the input coordinates and
+the output coordinates in hours and degrees to the output file. 
+
+.nf
+	cl> skyctran inlist outlist j1980.0 j2000.0 
+
+		... or equivalently ...
+
+	cl> skyctran inlist outlist j1980.0 2000.0
+
+		... or equivalently ...
+
+	cl> skyctran inlist outlist "fk5 1980.0" fk5
+.fi
+
+Note that if the coordinate system, e.g. fk5, is not specified explicitly
+then equinoxes < 1984 must be prefixed by J, or a Besselian rather than
+a Julian epoch will be assumed.
+
+3. Repeat the previous example but replace the input coordinates with
+the precessed coordinates in the output file.
+
+.nf
+	cl> skyctran inlist outlist j1980.0 j2000.0 transform+
+.fi
+
+4. Precess a list of RAS in hours and DECS in degrees in the FK4 system
+equinox 1950.0 to equinox 1975.0 and write both the input coordinates and
+the output coordinates in hours and degrees to the output file. The input
+and output epochs of observation default to the respective equinox
+values.
+
+.nf
+	cl> skyctran inlist outlist 1950.0 1975.0 
+
+		... or equivalently ...
+
+	cl> skyctran inlist outlist b1950.0 b1975.0 
+
+		... or equivalently ...
+
+	cl> skyctran inlist outlist fk4 b1975.0 
+
+		... or equivalently ...
+
+	cl> skyctran inlist outlist fk4 "fk4 1975.0" 
+.fi
+
+5. Convert a list of RAS in hours and DECS in degrees in the FK4 system
+equinox 1950.0 to RAS in hours and DECS in degrees in the FK5 system
+equinox 2000.0, and replace the input coordinates with the
+output coordinates in the output file. The Besselian epoch of the
+observation is 1987.25.
+
+.nf
+	cl> skyctran inlist outlist "b1950.0 1987.25" j2000.0 \
+	    transform+
+.fi
+
+6. Convert a list of RAS in hours and DECS in degrees to RAS in degrees
+and DECS in degrees, and replace the input coordinates with the output
+coordinates in the output file. As the input and output coordinate systems
+and equinoxes are the same no precession is performed.
+
+.nf
+	cl> skyctran inlist outlist 2000.0 2000.0 olngunits=degrees \
+	    transform+
+.fi
+
+7. Convert a list of RAS in hours and DECS in degrees in the FK4
+system, equinox 1950.0, epoch of observation 1987.24, to galactic
+coordinates, and write both the input and output coordinate to the
+output file.
+
+.nf
+	cl> skyctran inlist outlist "b1950.0 1987.25" galactic
+.fi
+
+8. Convert a list of RAS in hours and DECS in degrees in the FK5
+system, equinox 2000.0, to ecliptic coordinates on Julian date
+2449879.5, replacing the input coordinates with the converted
+coordinates in the output file.
+
+.nf
+	cl> skyctran inlist outlist j2000 "ecliptic 2449879.5" \
+	    transform+
+.fi
+
+9. Display an image and use the cursor and image header coordinate
+system, equatorial FK4, equinox 1950.0, epoch 1987.25  to print the pixel
+and galactic coordinates of the marked objects on the image display.
+Note that the test image dev$wpix has an incorrect value of EPOCH (0.0) that
+would have confused skyctran and need to be changed.
+
+.nf
+	cl> imcopy dev$wpix wpix
+	cl> hedit wpix epoch 1950.0
+	cl> display wpix 1 fi+
+	cl> skyctran imcursor STDOUT wpix galactic
+.fi
+
+10. Convert a list of RAS in hours and DECS in degrees measured in the
+image created in example 9 to the FK5 equinox 2000.0 coordinate system.
+
+.nf
+	cl> skyctran inlist outlist "wpix world" j2000.0
+
+		   ... or equivalently ...
+
+	cl> skyctran inlist outlist "b1950.0 1987.25" j2000.0
+.fi
+
+11. Using an image whose header coordinate system is equatorial FK5
+equinox 2000.0 and a different image of the same region whose coordinate
+system is galactic use the image display and cursor to create a list of
+tie points in logical pixel coordinates that can be used as input to the
+registration tasks geomap and geotran. Note that this example  and examples
+12 and 13 below will not work on iraf system earlier than 2.11 because galactic
+image header coordinates are not fully supported. They will work
+however on two images which have equatorial coordinates systems
+which are precessed with respect to each other.
+
+
+.nf
+	cl> display image1
+
+	    ... this is the reference image
+
+	cl> skyctran imcursor outlist image1 "image2 logical"
+
+	    ... mark many widely scattered points on the displayed
+		image image1 terminating the input list with 
+		<EOF> which is usually <ctrl/z> or <ctrl/d>
+.fi
+
+12. Repeat example 11 but use a previously prepared list of image1
+logical pixel coordinates as input to the task.
+
+.nf
+	cl> skyctran inlist outlist "image1 logical"\
+	    "image2 logical"
+.fi
+
+13. Repeat example 11 but have skyctran automatically generate a grid
+of 100 tie points.
+
+.nf
+	cl> skyctran grid outlist "image1 logical"\
+	    "image2 logical"
+.fi
+
+.ih
+TIME REQUIREMENTS
+.ih
+BUGS
+.ih
+SEE ALSO
+setjd,precess,galactic,xray.xspatial.skypix,stsdas.toolbox.tools.tprecess
+.endhelp